# dicelister

_Script to help generate custom Diceware wordlists yourself_

Dicelister helps generate Diceware wordlists from plain text files, webpages and basically any text you have around. A custom wordlist might help you strengthen your defences to protect your Diceware passphrases. With Dicelister you can also create wordlists localized for your language.

Dicelister has been written for mods and hacks in mind. Config files can override core variables and functions. If you know how to code, the sky is the limit! Use this to create wordlists with anything imaginable. Go ahead, be creative!

You can use [Dicemate](https://gitlab.com/adnan360/dicemate) to generate passphrases from your generated wordlists.

## Setup

You'll need Perl which is installed on most GNU+Linux and Unix systems by default. If running `perl -v` shows an error message instead of version info, install Perl.

Then install either `cpan` or `cpanm`. If they're not available in your system's software repo install cpanm with:

```
curl -L https://cpanmin.us | perl - App::cpanminus
```

This will install cpanm on userspace.

Then install required modules:

```
# for cpanm
cpanm -n Math::Base::Convert
cpanm -n HTTP::Tiny
cpanm -n Mojo::DOM
# for cpan
cpan -T Math::Base::Convert
cpan -T HTTP::Tiny
cpan -T Mojo::DOM
```

## Usage

### Quick start

```sh
cp config/example.pl config/mywordlist.pl
./dicelister.pl -c mywordlist -e
./dicelister.pl -c mywordlist -i
```

_Explanation:_

1. First command creates a copy of the example wordlist config.
2. Second one extracts words from data provided in config and prepares a rough wordlist file in `data/mywordlist.rough.txt` so that it can be edited to your needs.
3. After you review and edit the rough file, the third command will sort the words in rough file, add Diceware numbers before each word and save it to `data/mywordlist.wordlist.txt`.

Here, `-c` is for config, `-e` is for "extract" and `-i` is for indexing.

### Directory structure

Once you are prepared, look around the project to see how everything is organized.

- _(this directory)_: Has the main dicelister.pl file, README.md and other things related to the project. This directory does not usually need any edits if you just want to generate a wordlist. But you can read `dicelister.pl` file for understanding how everything works. Your config files basically override variables and subroutines (aka functions) in this file to get what you want.
- `config`: Has all the configs. Wordlists are generated based on values and functions within the config files in this directory. If you are new, copy `example.pl` and start experimenting.
- `data`: Has all the data and outputs for the wordlist. All the sources you use should ideally be in this directory. If you use any webpages as source it could be downloaded here.
	- `data/example.rough.txt` - After the words are extracted, the unique words are sorted alphabetically and put into this file. This file can be edited freely, for example, you can remove any words, edit any words to you liking or even add words if you feel like it.
	- `data/example.wordlist.txt` - After the `-i` command is run, the words in the `example.rough.txt` are sorted once again and Diceware numbers are added before each word so that it can be used, printed or whatever.

### Hooks

Hooks are a great way to plug in to the process of Dicelister. You can do different things in between Dicelister steps. This is in addition to the overridable functions - in case you don't want to override any function, but still want to add something by yourself.

If more hooks are necessary, feel free to post an issue.

#### Hook usage

Search for `# Hook:` in the `dicelister.pl` file and use it in your config file to do something as you please.

For example:

```perl
sub dicelister::after_indexed_file_write {
	print "Wordlist prepared! Enjoy!!\n";
}
```

If you add this to config file it will print a message when the wordlist file is ready.

#### Hook list

##### `after_config_import`

Runs after config file is imported or `require`-d.

##### `before_rough_file_process`

Runs before rough file creation process starts.

##### `before_rough_file_write`

Runs before rough file creation process starts.

##### `after_rough_file_write`

Runs after rough file creation process ends.

##### `before_indexed_file_process`

Runs before indexed file creation process starts.

##### `before_indexed_file_write`

Runs before indexed file write process starts.

##### `after_indexed_file_write`

Runs after indexed file write process ends.
